开发者调用远程 MCP 服务

开发者可以在自己的 AI Agent 或自动化工作流中，通过代码集成的形式，调用飞书 MCP 提供的工具能力，以实现更复杂的定制化业务逻辑。 远程调用模式允许开发者通过一个唯一的服务 URL，直接连接到飞书官方部署和维护的 MCP 服务。这种模式免去了本地部署和环境配置的复杂性，让你能以最快速度将飞书能力集成到 AI Agent 中。 当前支持「云文档」场景，查看 支持的 MCP 工具集 章节。欢迎反馈您的使用场景 🥳

开发前准备

在开始接入前，请确保你已完成以下准备工作： 1. 创建自建应用：在 飞书开放平台 创建一个自建应用。 1. 申请权限：根据你的工具需要，为应用申请对应的 API 权限。例如，如果你的工具需要读写云文档，则必须申请“查看、评论和管理云空间文档” (drive:document) 等相关权限。参考 申请 API 权限。 1. 获取访问凭证： - User Access Token (UAT) ：代表用户身份的凭证，适用于需要模拟特定用户操作的场景。获取方式请参考 获取 user_access_token。 - Tenant Access Token (TAT) ：代表应用身份的凭证，适用于服务端到服务端的调用场景。获取方式请参考 获取 tenant_access_token。

支持的 MCP 工具warning

• MCP 工具入参、出参格式可能灵活调整，调用 MCP 时请勿依赖入参和出参的结构定义。
• 如涉及多个权限，请全部申请。请根据你的调用身份（UAT 或 TAT），参考 申请 API 权限 完成开通。

通用工具

工具名称	功能描述	功能限制	典型场景	支持 UAT/TAT	所需权限
search-user	根据关键词搜索企业内的用户，可获取用户的 ID、姓名、头像。 注意事项：如有同名用户，则按照亲密度返回，与你更亲密的用户排序靠前。	- 仅支持通过用户身份（user_access_token）调用该接口。 - 无法搜索到外部企业或已离职的用户。	- 在不知道准确 ID 的情况下，通过姓名或邮箱快速查找同事。 - 需要联系某人或分配任务，但只记得对方名字的一部分，用于定位具体人员。	UAT	- 搜索用户 contact:user:search
get-user	获取用户本人的个人信息，也可通过用户 ID 获取其他用户的姓名、头像。	- 用户信息仅包含：用户头像、名称、open id - 仅可查询你在通讯录中可见的用户范围，详见管理员设置 [组织架构可见性](https://www.feishu.cn/hc/zh-CN/articles/360049067480-%E7%AE%A1%E7%90%86%E5%91%98%E7%AE%A1%E7%90%86%E7%BB%84%E7%BB%87%E6%9E%B6%E6%9E%84%E5%8F%AF%E8%A7%81%E8%8C%83%E5%9B%B4#tabs0	lineguid-Gu5cE)。	- 查询当前登录用户的个人信息（如确认自己的 open id）。 - 在已知用户 ID 的情况下（例如从搜索结果中获得），获取该员工的头像和名称。	UAT/TAT TAT 调用时，通讯录权限范围需要包含对应用户
fetch-file	获取文件内容。根据文件 ID (file_token)，获取文档中指定资源（文件或图片）的二进制内容。	- 文件大小限制在 5 MB 以内 - 需要有素材的下载权限，即文档「权限设置」中，当前用户拥有下载权限，如下图：	- 读取云文档中嵌入的图片、图表或附件。 - 在自动化流程中，获取文档内特定资源的原始二进制数据以供后续处理。	UAT/TAT	- 下载云文档中的图片和附件 docs:document.media:download - 查看画板节点 board:whiteboard:node:read

云文档

若使用 TAT 调用，请确保应用已获得目标文档/知识库的授权，参考 如何为应用或用户开通文档权限。

接入流程

第 1 步：初始化连接 (initialize)

与 MCP 服务建立连接并验证凭证，返回会话信息。

POST /mcp
Header: X-Lark-MCP-TAT: t-gxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
X-Lark-MCP-Allowed-Tools:toolname1,toolname2,toolname3
Body: {"method": "initialize", ...}

第 2 步：列出可用工具 (tools/list)

查询当前凭证和 X-Lark-MCP-Allowed-Tools 中定义的 MCP 工具列表和工具描述。

POST /mcp
Header: 
X-Lark-MCP-TAT: t-gxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
X-Lark-MCP-Allowed-Tools:toolname1,toolname2,toolname3
Body: {"method": "tools/list", ...}

第 3 步：调用工具 (tools/call)

执行一个具体的工具（要求该工具必须在请求 Header X-Lark-MCP-Allowed-Tools 列表中）。

POST /mcp
Header:
Content-Type: application/json
X-Lark-MCP-TAT: t-gxxxxxxxxxxxxxxxxxxxxx
X-Lark-MCP-Allowed-Tools:toolname1,toolname2,toolname3
Body: {"method": "tools/call", "params": {"name": "toolname1", ...}}

认证与请求

请求路径

所有 MCP 的 API 请求都使用统一的端点和 HTTP 方法。

• HTTP URL：https://mcp.feishu.cn/mcp
• HTTP Method：POST

请求头

MCP 通过 HTTP 请求头进行认证和配置。

请求体

所有请求体都遵循 JSON-RPC 2.0 规范，包含以下核心字段： - jsonrpc: (string) JSON-RPC 协议版本，固定为 "2.0"。 - id: (integer) 请求的唯一标识符，用于关联请求和响应。 - method: (string) 要调用的方法名称。

示例如下：

POST /mcp HTTP/1.1
Host: mcp.feishu.cn
Content-Type: application/json
X-Lark-MCP-UAT: u-gxxxxxxxxxxxxxxxxxxxxx
X-Lark-MCP-Allowed-Tools: create-doc,fetch-doc
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize"
}

支持的 MCP 方法

常见框架示例代码

Nodejs

• Langchain：官方文档
• ai-sdk：官方文档
• typescript-sdk：官方文档

Python

• Langchain：官方文档
• Python-sdk：官方文档

Go

• Eino：官方文档
• mcp-go：官方文档
• Go-sdk：官方文档

Java

• Java-sdk：官方文档
• Spring：官方文档

错误码

错误响应格式

• 工具执行失败: 当 API 请求成功，但工具内部执行出错时，HTTP 状态码仍为 200，但在 result 对象中通过 isError: true 和 content 中的错误信息来体现。

{
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
        "content": [
            {
                "type": "text",
                "text":"{"error":"[VALIDATION:1004] Document ID length is insufficient: 13 < 15\n💡 Suggestion: Please check if the document token is complete\n📍 Context: docID=ewqedwqeqwewq, length=13","log_id":"202512112222588228F6885BAECF6F6987"}"
            }
        ],
        "isError": true
    }
}

• 调用失败：当请求本身不合法（如认证失败、方法名错误）时，会直接返回顶层的 error 对象。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}